.so ../bk-macros
.TH "bk glob" "\*[BKVER]" 20%E% "\*(BC" "\*(UM"
.SH NAME
bk glob \- demo program to show glob pattern expansion
.SH SYNOPSIS
.B bk glob
.ARG pattern
.ARG string
[\c
.ARG string
.ARG string " .\|.\|.]"
.SH DESCRIPTION
.LP
Some \*(BK interfaces use what are called \*(lqglob patterns,\*(rq
sometimes known as wild cards.
Examples include the configuration file, history listing (\fBbk changes\fP), and
file name expansion (\fBbk files\fR).
.LP
This command may be used to match a glob against one or more strings to see
examples of how the pattern matching works.
.SH WILDCARD MATCHING
A string is a glob pattern if it contains one of the characters
\*(lq*\*(rq,
\*(lq?\*(rq,
\*(lq[\*(rq,
or sometimes
\*(lq=\*(rq.
(The last one, \*(lq=\*(rq, is an alias for \*(lq*\*(rq, to avoid shell quoting in many cases.
See \s-2CONFIGURATION\s0 below.)
The glob pattern is used to match one or more strings (or file names), usually
in a process that takes a glob pattern and a list of possible matches and 
returns the subset of the list which matches the glob pattern.  Matching
works as follows:
.SP
.TP \fB[^.\|.\|.]\fP
.B ?
Matches any single character (unless \*(lq?\*(rq is between brackets).
.SP
.tp
.B *
Matches any string (unless \*(lq*\*(rq is between brackets).
.SP
.tp
.B [\fR.\|.\|.\fP]
A set of characters enclosed in brackets matches a single character if and
only if the character is in the set.
.SP
.tp
.B [^\fR.\|.\|.\fP]
As above but inverts the set.
In other words \*(lq[^abc]\*(rq matches any character except
\*(lqa\*(rq, \*(lqb\*(rq, or \*(lqc\*(rq.
.SH CONFIGURATION
It is possible to disable all use of globs in file name expansion by setting
the environment variable
.V BK_NO_FILE_GLOB
to any value.
.LP
Since aliasing \*(lq=\*(rq for \*(lq*\*(rq is not a standard feature and it may
cause problems when processing files with \*(lq=\*(rq as part of their
name, it must be explicitly  enabled by setting
.V BK_GLOB_EQUAL
to the value of
.BR YES .
No other value will enable this feature.
.SH EXAMPLES
Test a simple pattern match that matches file.c and file.h:
.DS
bk glob '*.[ch]' file.c file.h file.1
.DE
List all files ending in \*(lq.1\*(rq:
.DS
export BK_GLOB_EQUAL=YES
bk -A files =.1
.DE
See changes in all header files in the current directory:
.DS
bk diffs '*.h'
.DE
See the revision history for all C/header files with the phrase
\*(lqsccs\*(rq in their name:
.DS
bk sccslog '*sccs*.[ch]'
.DE
See all changesets which include the phrase \*(lqBUGID:\*(rq
followed by a number:
.DS
bk changes '-/BUGID:[123456789]/'
.DE
.SH BUGS
Sets of characters, i.e., [A-Z], have only marginal support.  
Escaping the minus in the set is not supported.
.SH SEE ALSO
.SA config-etc
.SA changes
.SA files
.SH CATEGORY
.B File
.br
.B Repository
